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ABOUT THIS CHAPTER 


This chapter gives you general information that you'll need to write all or part 
of your Macintosh application program in assembly language. It assumes you 


already know how to write assembly-language programs for the Motorola MC68000, 
the microprocessor in the Macintosh. 
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DEFINITION FILES 


The primary aids to assembly-language programmers are a set of definition files 
for symbolic names used in assembly-language programs. The definition files 
include equate files, which equate symbolic names with values, and macro files, 
which define the macros used to call Toolbox and Operating System routines from 
assembly language. The equate files define a variety of symbolic names for 
various purposes, such as: 


useful numeric quantities 

masks and bit numbers 

offsets into data structures 

addresses of global variables (which in turn often contain addresses) 


eeee 


It's a good idea to always use the symbolic names defined in an equate file in 
place of the corresponding numeric values (even if you know them), since some of 
these values may change. Note that the names of the offsets for a data structure 
don't always match the field names in the corresponding Pascal definition. In 
the documentation, the definitions are normally shown in their Pascal form; the 
corresponding offset constants for assembly language use are listed in the 
summary at the end of each chapter. 


Some generally useful global variables defined in the equate files are as 
follows: 


Name Contents 

OneOne $00010001 

MinusOne $FFFFFFFF 

Lo3Bytes SOOFFFFFF 

Scratch20 20-byte scratch area 

Scratch8 8-byte scratch area 

ToolScratch 8-byte scratch area 

ApplScratch 12-byte scratch area reserved for use by applications 


Scratch20, Scratch8, and ToolScratch will not be preserved across calls to the 
routines in the Macintosh ROM. ApplScratch will be preserved; it should be used 
only by application programs and not by desk accessories or other drivers. 


Other global variables are described where relevant in Inside Macintosh. A list 
of all the variables described is given in Appendix D. 
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PASCAL DATA TYPES 


Pascal's strong typing ability lets Pascal programmers write programs without 
really considering the size of variables. But assembly language programmers must 
keep track of the size of every variable. The sizes of the standard Pascal data 
types, and some of the basic types defined in the Memory Manager, are listed 
below. (See the Apple Numerics Manual for more information about SINGLE, DOUBLE, 
EXTENDED, and COMP.) 


Type Size Contents 

INTEGER 2 bytes Two's complement integer 

LONGINT 4 bytes Two's complement integer 

BOOLEAN 1 byte Boolean value in bit 0 

CHAR 2 bytes Extended ASCII code in low-order byte 


SINGLE (or REAL) 
4 bytes IEEE standard single format 
DOUBLE 8 bytes IEEE standard double format 
EXTENDED 10 bytes IEEE standard extended format 
COMP (or COMPUTATIONAL) 
8 bytes Two's complement integer with reserved value 
STRING[n] n+1 bytes Byte containing string length (not counting 
length byte) followed by bytes containing 
ASCII codes of characters in string 
SignedByte 1 byte Two's complement integer 


Byte 2 bytes Value in low-order byte 
Ptr 4 bytes Address of data 
Handle 4 bytes Address of master pointer 


Other data types are constructed from these. For some commonly used data types, 
the size in bytes is available as a predefined constant. 


Before allocating space for any variable whose size is greater than one byte, 
Pascal adds "padding" to the next word boundary, if it isn't already at a word 
boundary. It does this not only when allocating variables declared successively 
in VAR statements, but also within arrays and records. As you would expect, the 
Size of a Pascal array or record is the sum of the sizes of all its elements or 
fields (which are stored with the first one at the lowest address). For example, 
the size of the data type 


TYPE TestRecord = RECORD 
testHandle: Handle; 
testBoolA: BOOLEAN; 
testBoolB: BOOLEAN; 
testChar: CHAR 
END; 


is eight bytes: four for the handle, one each for the Booleans, and two for the 
character. If the testBoolB field weren't there, the size would be the same, 
because of the byte of padding Pascal would add to make the character begin on a 
word boundary. 
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In a packed record or array, type BOOLEAN is stored as a bit, and types CHAR and 
Byte are stored as bytes. The padding rule described above still applies. For 
example, if the TestRecord data type shown above were declared as PACKED RECORD, 
it would occupy only six bytes: four for the handle, one for the Booleans (each 
stored in a bit), and one for the character. If the last field were INTEGER 
rather than CHAR, padding before the two byte integer field would cause the size 
to be eight bytes. 


Note: The packing algorithm may not be what you expect. If you need to know 
exactly how data is packed, or if you have questions about the size of 
a particular data type, the best thing to do is write a test program 
in Pascal and look at the results. (You can use the SIZEOF function to 
get the size.) 
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THE TRAP DISPATCH TABLE 


The Toolbox and Operating System reside in ROM. However, to allow flexibility 
for future development, application code must be kept free of any specific ROM 
addresses. So all references to Toolbox and Operating System routines are made 
indirectly through the trap dispatch table in RAM, which contains the addresses 
of the routines. As long as the location of the trap dispatch table is known, 
the routines themselves can be moved to different locations in ROM without 
disturbing the operation of programs that depend on them. 


Information about the locations of the various Toolbox and Operating System 
routines is encoded in compressed form in the ROM itself. When the system starts 
up, this encoded information is expanded to form the trap dispatch table. 
Because the trap dispatch table resides in RAM, individual entries can be 
"patched" to point to addresses other than the original ROM address. This allows 
changes to be made in the ROM code by loading corrected versions of individual 
routines into RAM at system startup and patching the trap dispatch table to 
point to them. It also allows an application program to replace specific Toolbox 
and Operating System routines with its own "custom" versions. A pair of utility 
routines for manipulating the trap dispatch table, GetTrapAddress and 
SetTrapAddress, are described in the Operating System Utilities chapter. 


In the 64K ROM, references to both Toolbox and Operating System routines are 
made through a single trap dispatch table. For compactness, entries in that 
table are encoded into one word each. The high-order bit of each entry tells 
whether the routine resides in ROM (0) or RAM (1). The remaining 15 bits give 
the offset of the routine relative to a base address. For routines in ROM, this 
base address is the beginning of the ROM; for routines in RAM, it's the 
beginning of the system heap. The two base addresses are kept in a pair of 
global variables named ROMBase and RAMBase. Using 15-bit unsigned word offsets, 
the range of locations that the trap dispatch table can address is limited to 
64K bytes. Also, the interleaving of Operating System and Toolbox trap numbers 
limits the total number of traps to 512 and means that no two traps can be 
represented by the same number. 


In the 128K ROM, the Toolbox and Operating System traps have separate dispatch 
tables. Instead of a packed format, entries in these dispatch tables are stored 
as full long-word addresses so the dispatcher makes no distinction between ROM 
and RAM addresses. The Operating System dispatch table consists of 256 long 
words, from address $400 through $7FF; this replaces the old dispatch table of 
512 words. The Toolbox table consists of 512 long words, from address $C00 
through $13FF. 


Warning: The format of the trap dispatch tables may be different in future 
versions of Macintosh system software. If it's absolutely necessary 
that you manipulate the trap dispatch tables, use the Operating 
System Utility routines NGetTrapAddress and NSetTrapAddress (or with 
the 64K ROM, GetTrapAddress and SetTrapAddress); they're described 
in the Operating System Utilities chapter. 
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The offset in a trap dispatch table entry is expressed in words instead of 
bytes, taking advantage of the fact that instructions must always fall on word 
boundaries (even byte addresses). AS illustrated in Figure 1, the system does 
the following to find the absolute address of the routine: 


1. checks the high-order bit of the trap dispatch table entry to find 
out which base address to use 

2. doubles the offset to convert it from words to bytes (by left shifting 
one bit) 

3. adds the result to the designated base address 


Trap Dispatch Table Entry 


in id 0 
— L 
15 i a 
O: (ROPBase] " — address of 
1: (RAM Base] rowtine 


Figure 1-Trap Dispatch Table Entry 


Figure 1—Trap Dispatch Table Entry 


Using 15-bit word offsets, the trap dispatch table can address locations within 
a range of 32K words, or 64K bytes, from the base address. Starting from 
ROMBase, this range is big enough to cover the entire ROM; but only slightly 
more than half of the 128K RAM lies within range of RAMBase. RAMBase is set to 
the beginning of the system heap to maximize the amount of useful space within 
range; locations below the start of the heap are used to hold global system data 
and can never contain executable code. If the heap is big enough, however, it's 
possible for some of the application's code to lie beyond the upper end of the 
trap dispatch table's range. Any such code is inaccessible through the trap 
dispatch table. 


Note: This problem is particularly acute on the Macintosh 512K and 
Macintosh XL. To make sure they lie within range of RAMBase, 
patches to Toolbox and Operating System routines are typically 
placed in the system heap rather than the application heap. 
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THE TRAP MECHANISM 


Calls to the Toolbox and Operating System via the trap dispatch table are 
implemented by means of the MC68000's "1010 emulator" trap. To issue such a call 
in assembly language, you use one of the trap macros defined in the macro files. 
When you assemble your program, the macro generates a trap word in the machine 
language code. A trap word always begins with the hexadecimal digit $A 

(binary 1010); the rest of the word identifies the routine you're calling, along 
with some additional information pertaining to the call. 


Note: A list of all Macintosh trap words is given in Appendix C. 


Instruction words beginning with $A or $F ("A-line" or "F-line" instructions) 
don't correspond to any valid machine language instruction, and are known as 
unimplemented instructions. They're used to augment the processor's native 
instruction set with additional operations that are "emulated" in software 
instead of being executed directly by the hardware. A-line instructions are 
reserved for use by Apple; on a Macintosh, they provide access to the Toolbox 
and Operating System routines. Attempting to execute such an instruction causes 
a trap to the trap dispatcher, which examines the bit pattern of the trap word 
to determine what operation it stands for, looks up the address of the 
corresponding routine in the trap dispatch table, and jumps to the routine. 


Note: F-line instructions are reserved by Motorola for use in future 
processors. 


Format of Trap Words 


As noted above, a trap word always contains $A in bits 12-15. Bit 11 determines 
how the remainder of the word will be interpreted; usually it's 0 for Operating 
System calls and 1 for Toolbox calls, though there are some exceptions. 


Figure 2 shows the Toolbox trap word format. Bits 0-8 form the trap number (an 
index into the trap dispatch table), identifying the particular routine being 
called. Bit 9 is reserved for future use. Bit 10 is the “auto-pop" bit; this bit 
is used by language systems that, rather than directly invoking the trap like 
Lisa Pascal, do a JSR to the trap word followed immediately by a return to the 
calling routine. In this case, the return addresses for the both the JSR and the 
trap get pushed onto the stack, in that order. The auto-pop bit causes the trap 
dispatcher to pop the trap's return address from the stack and return directly 
to the calling program. 
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Figure 2-Toolbor Trap Word (Bit 11=1) 
Figure 2—Toolbox Trap Word (Bit 11=1) 


For Operating System calls, only the low order eight bits (bits 0-7) are used 
for the trap number (see Figure 3). Thus of the 512 entries in the trap dispatch 
table, only the first 256 can be used for Operating System traps. Bit 8 of an 
Operating System trap has to do with register usage and is discussed below under 
"Register Saving Conventions". Bits 9 and 10 have specialized meanings depending 
on which routine you're calling, and are covered where relevant in other 
chapters. 
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Figure 3-Operating System Trap Yor (Bit 11=0) 
Figure 3—Operating System Trap Word (Bit 11=0) 


As described above, a trap word begins with the hexadecimal digit $A (binary 
1010); the rest of the word identifies the routine you're calling, along with 
additional information pertaining to the call. 


In the 64K ROM, an Operating System trap and a Toolbox trap cannot have the same 
trap number; the GetTrapAddress and SetTrapAddress routines do not distinguish 
between Toolbox and Operating System traps. 


Since each group has its own dispatch table in the 128K ROM, there can be a 
Toolbox trap and an Operating System trap with the same trap number. Two new 
routines-NGetTrapAddress and NSetTrapAddress—have been added; they use bits 9 
and 10 of their trap word for specifying the group to which a routine belongs. 


Trap Macros 


The names of all trap macros begin with the underscore character (_), followed 


by the name of the corresponding routine. As a rule, the macro name is the same 
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as the name used to call the routine from Pascal, as given in the Toolbox and 
Operating System documentation. For example, to call the Window Manager routine 
NewWindow, you would use an instruction with the macro name _NewWindow in the 
opcode field. There are some exceptions, however, in which the spelling of the 
macro name differs from the name of the Pascal routine itself; these are noted 
in the documentation for the individual routines. 


Note: The reason for the exceptions is that assembler names must be unique 
to eight characters. Since one character is taken up by the underscore, 
special macro names must be used for Pascal routines whose names aren't 
unique to seven characters. 


Trap macros for Toolbox calls take no arguments; those for Operating System 
calls may have as many as three optional arguments. The first argument, if 
present, is used to load a register with a parameter value for the routine 
you're calling, and is discussed below under "Register Based Routines". The 
remaining arguments control the settings of the various flag bits in the trap 
word. The form of these arguments varies with the meanings of the flag bits, and 
is described in the chapters on the relevant parts of the Operating System. 
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CALLING CONVENTIONS 


The calling conventions for Toolbox and Operating System routines fall into two 
categories: stack based and register based. As the terms imply, stack based 
routines communicate via the stack, following the same conventions used by the 
Pascal Compiler for routines written in Lisa Pascal, while register based 
routines receive their parameters and return their results in registers. Before 
calling any Toolbox or Operating System routine, you have to set up the 
parameters in the way the routine expects. 


Note: As a general rule, Toolbox routines are stack based and Operating 
System routines register based, but there are exceptions on both sides. 
Throughout Inside Macintosh, register based calling conventions are 
given for all routines that have them; if none is shown, then the 
routine is stack based. 


Stack-Based Routines 


To call a stack based routine from assembly language, you have to set up the 
parameters on the stack in the same way the compiled object code would if your 
program were written in Pascal. If the routine you're calling is a function, its 
result is returned on the stack. The number and types of parameters, and the 
type of result returned by a function, depend on the routine being called. The 
number of bytes each parameter or result occupies on the stack depends on its 


type: 


Type of parameter 
or function 


result Size Contents 

INTEGER 2 bytes Two's complement integer 

LONGINT 4 bytes Two's complement integer 

BOOLEAN 2 bytes Boolean value in bit 0 of high-order byte 
CHAR 2 bytes Extended ASCII code in low-order byte 


SINGLE (or REAL), DOUBLE, COMP (or COMPUTATIONAL) 
4 bytes Pointer to value converted to EXTENDED 
EXTENDED 4 bytes Pointer to value 
STRING[n] 4 bytes Pointer to string (first byte 
pointed to is length byte) 


SignedByte 2 bytes Value in low-order byte 

Byte 2 bytes Value in low-order byte 

Ptr 4 bytes Address of data 

Handle 4 bytes Address of master pointer 

Record or array 2 or 4 Contents of structure (padded to 


bytes word boundary) if <= 4 bytes, 
otherwise pointer to structure 
VAR parameter 4 bytes Address of variable, regardless of type 


The steps to take to call the routine are as follows: 
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1. If it's a function, reserve space on the stack for the result. 

2. Push the parameters onto the stack in the order they occur in 
the routine's Pascal definition. 

3. Call the routine by executing the corresponding trap macro. 


The trap pushes the return address onto the stack, along with an extra word of 
processor status information. The trap dispatcher removes this extra status 
word, leaving the stack in the state shown in Figure 4 on entry to the routine. 
The routine itself is responsible for removing its own parameters from the stack 
before returning. If it's a function, it leaves its result on top of the stack 
in the space reserved for it; if it's a procedure, it restores the stack to the 
same state it was in before the call. 


Ligh memory high memory 


previous shack contents previous stack contents 
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low memory 


on tw teetions 
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On entry 
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Figure 4-Stack Format for Stack-Based Routines 


Figure 4-Stack Format for Stack Based Routines 


For example, the Window Manager function GrowWindow is defined in Pascal as 
follows: 


FUNCTION GrowWindow (theWindow: WindowPtr; startPt: Point; 
sizeRect: Rect) : LONGINT; 


To call this function from assembly language, you'd write something like the 
following: 


SUBQ.L #4,SP ;make room for LONGINT result 
MOVE.L theWindow,-(SP) ;push window pointer 
MOVE.L startPt, - (SP) ;a Point is a 4-byte record, 
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;so push actual contents 


PEA SsizeRect ;a Rect is an 8-byte record, 
;so push a pointer to it 

_GrowWindow ;trap to routine 

MOVE.L (SP)+,D3 ;pop result from stack 


Although the MC68000 hardware provides for separate user and supervisor stacks, 
each with its own stack pointer, the Macintosh maintains only one stack. All 
application programs run in supervisor mode and share the same stack with the 
system; the user stack pointer isn't used. 


Warning: For compatibility with future versions of the Macintosh, your 
program should not rely on capabilities available only in 
Supervisor mode (such as the instruction RTE). 


Remember that the stack pointer must always be aligned on a word boundary. This 
is why, for example, a Boolean parameter occupies two bytes; it's actually the 
Boolean value followed by a byte of padding. Because all Macintosh application 
code runs in the MC68000's supervisor mode, an odd stack pointer will cause a 
"double bus fault": an unrecoverable system failure that causes the system to 
restart. 


To keep the stack pointer properly aligned, the MC68000 automatically adjusts 
the pointer by 2 instead of 1 when you move a byte length value to or from the 
stack. This happens only when all of the following three conditions are met: 


e A one byte value is being transferred. 
¢ Either the source or the destination is specified by 
predecrement or postincrement addressing. 
« The register being decremented or incremented is the stack pointer (A7). 


An extra, unused byte will automatically be added in the low order byte to keep 
the stack pointer even. (Note that if you need to move a character to or from 
the stack, you must explicitly use a full word of data, with the character in 
the low order byte.) 


Warning: If you use any other method to manipulate the stack pointer, it's 
your responsibility to make sure the pointer stays properly aligned. 


Note: Some Toolbox and Operating System routines accept the address of 
one of your own routines as a parameter, and call that routine under 
certain circumstances. In these cases, you must set up your routine 
to be stack based. 


Register-Based Routines 


By convention, register based routines normally use register AO for passing 
addresses (such as pointers to data objects) and DO for other data values (such 
as integers). Depending on the routine, these registers may be used to pass 
parameters to the routine, result values back to the calling program, or both. 
For routines that take more than two parameters (one address and one data 
value), the parameters are normally collected in a parameter block in memory and 
a pointer to the parameter block is passed in AQ. However, not all routines obey 
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these conventions; for example, some expect parameters in other registers, such 
as Al. See the description of each individual routine for details. 


Whatever the conventions may be for a particular routine, it's up to you to set 
up the parameters in the appropriate registers before calling the routine. For 
instance, the Memory Manager procedure BlockMove, which copies a block of 
consecutive bytes from one place to another in memory, expects to find the 
address of the first source byte in register AQ, the address of the first 
destination location in Al, and the number of bytes to be copied in DO. So you 
might write something like 


LEA src(A5) ,A0 ssource address in AQ 

LEA dest(A5),Al1 sdestination address in Al 
MOVEQ #20,D0 ;byte count in DO 
_BlockMove ; trap to routine 


Macro Arguments 


The following information applies to the Lisa Workshop Assembler. If you're 
using some other assembler, you should check its documentation to find out 
whether this information applies. 


Many register based routines expect to find an address of some sort in register 
AQ. You can specify the contents of that register as an argument to the macro 
instead of explicitly setting up the register yourself. The first argument you 
supply to the macro, if any, represents an address to be passed in AQ. The macro 
will load the register with an LEA (Load Effective Address) instruction before 
trapping to the routine. So, for instance, to perform a Read operation on a 
file, you could set up the parameter block for the operation and then use the 
instruction 


_ Read paramBlock ;trap to routine with pointer to 
; parameter block in AO 


This feature is purely a convenience, and is optional: If you don't supply any 
arguments to a trap macro, or if the first argument is null, the LEA to AO will 
be omitted from the macro expansion. Notice that AO is loaded with the address 
denoted by the argument, not the contents of that address. 


Note: You can use any of the MC68000's addressing modes to specify this 
address, with one exception: You can't use the two register indexing 
mode ("address register indirect with index and displacement"). An 
instruction such as 


_Read offset(A3,D5) 


won't work properly, because the comma separating the two registers 
will be taken as a delimiter marking the end of the macro argument. 


Result Codes 


Many register-based routines return a result code in the low order word of 
register DO to report successful completion or failure due to some error 
condition. A result code of 0 indicates that the routine was completed 
successfully. Just before returning from a register based call, the trap 
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dispatcher tests the low order word of DO with a TST.W instruction to set the 
processor's condition codes. You can then check for an error by branching 
directly on the condition codes, without any explicit test of your own. For 
example: 


_PurgeMem ;trap to routine 
BEQ NoError sbranch if no error 
shandle error 


Warning: Not all register based routines return a result code. Some leave 
the contents of DO unchanged; others use the full 32 bits of the 
register to return a long word result. See the descriptions of 
individual routines for details. 


Register-Saving Conventions 


ALL Toolbox and Operating System routines preserve the contents of all registers 
except AO, Al, and DO-D2 (and of course A7, which is the stack pointer). In 
addition, for register based routines, the trap dispatcher saves registers Al, 
D1, and D2 before dispatching to the routine and restores them before returning 
to the calling program. A7 and DO are never restored; whatever the routine 
leaves in these registers is passed back unchanged to the calling program, 
allowing the routine to manipulate the stack pointer as appropriate and to 
return a result code. 


Whether the trap dispatcher preserves register AQ for a register based trap 
depends on the setting of bit 8 of the trap word: If this bit is 0, the trap 
dispatcher saves and restores AO; if it's 1, the routine passes back AO 
unchanged. Thus bit 8 of the trap word should be set to 1 only for those 
routines that return a result in AO, and to © for all other routines. The trap 
macros automatically set this bit correctly for each routine, so you never have 
to worry about it yourself. 


Stack based traps preserve only registers A2-A6 and D3-D7. If you want to 
preserve any of the other registers, you have to save them yourself before 
trapping to the routine - typically on the stack with a MOVEM (Move Multiple) 
instruction - and restore them afterward. 


Warning: When an application starts up, register A5 is set to point to the 
boundary between the application globals and the application 
parameters (see the memory map in the Memory Manager chapter for 
details). Certain parts of the system rely on finding A5 set up 
properly (for instance, the first application parameter is a 
pointer to the first QuickDraw global variable), so you have to 
be a bit more careful about preserving this register. The safest 
policy is never to touch A5 at all. If you must use it for your 
own purposes, just saving its contents at the beginning of a 
routine and restoring them before returning isn't enough: You 
have to be sure to restore it before any call that might depend 
on it. The correct setting of A5 is always available in the global 
variable CurrentA5. 


Note: Any routine in your application that may be called as the result 
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of a Toolbox or Operating System call shouldn't rely on the value 
of any register except A5, which shouldn't change. 


Pascal Interface to the Toolbox and Operating System 


When you call a register based Toolbox or Operating System routine from Pascal, 
you're actually calling an interface routine that fetches the parameters from 
the stack where the Pascal calling program left them, puts them in the registers 
where the routine expects them, and then traps to the routine. On return, it 
moves the routine's result, if any, from a register to the stack and then 
returns to the calling program. (For routines that return a result code, the 
interface routine may also move the result code to a global variable, where it 
can later be accessed. ) 


For stack-based calls, there's no interface routine; the trap word is inserted 
directly into the compiled code. 
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MIXING PASCAL AND ASSEMBLY LANGUAGE 


You can mix Pascal and assembly language freely in your own programs, calling 
routines written in either language from the other. The Pascal and assembly 
language portions of the program have to be compiled and assembled separately, 
then combined with a program such as the Lisa Workshop Linker. For convenience 
in this discussion, such separately compiled or assembled portions of a program 
will be called "modules". You can divide a program into any number of modules, 
each of which may be written in either Pascal or assembly language. 


References in one module to routines defined in another are called external 
references, and must be resolved by a program like the Linker that matches them 
up with their definitions in other modules. You have to identify all the 
external references in each module so they can be resolved properly. For more 
information, and for details about the actual process of linking the modules 
together, see the documentation for the development system you're using. 


In addition to being able to call your own Pascal routines from assembly 
language, you can call certain routines in the Toolbox and Operating System that 
were created expressly for Lisa Pascal programmers and aren't part of the 
Macintosh ROM. (These routines may also be available to users of other 
development systems, depending on how the interfaces have been set up on those 
systems.) They're marked with the notation 


[Not in ROM] 


in Inside Macintosh. There are no trap macros for these routines (though they 
may call other routines for which there are trap macros). Some of them were 
created just to allow Pascal programmers access to assembly language 
information, and so won't be useful to assembly language programmers. Others, 
however, contain code that's executed before a trap macro is invoked, and you 
may want to perform the operations they provide. 


All calls from one language to the other, in either direction, must obey 
Pascal's stack based calling conventions (see "Stack Based Routines", above). To 
call your own Pascal routine from assembly language, or one of the Toolbox or 
Operating System routines that aren't in ROM, push the parameters onto the stack 
before the call and (if the routine is a function) look for the result on the 
stack on return. In an assembly language routine to be called from Pascal, look 
for the parameters on the stack on entry and leave the result (if any) on the 
stack before returning. 


Under stack based calling conventions, a convenient way to access a routine's 
parameters on the stack is with a frame pointer, using the MC68000's LINK and 
UNLK (Unlink) instructions. You can use any address register for the frame 
pointer (except A7, which is reserved for the stack pointer), but register A6 is 
conventionally used for this purpose on the Macintosh. The instruction 


LINK A6 ,#-12 
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at the beginning of a routine saves the previous contents of A6 on the stack and 
sets A6 to point to it. The second operand specifies the number of bytes of 
stack space to be reserved for the routine's local variables: in this case, 12 
bytes. The LINK instruction offsets the stack pointer by this amount after 
copying it into A6. 


Warning: The offset is added to the stack pointer, not subtracted from it. 
So to allocate stack space for local variables, you have to give 
a negative offset; the instruction won't work properly if the 
offset is positive. Also, to keep the stack pointer correctly 
aligned, be sure the offset is even. For a routine with no local 
variables on the stack, use an offset of #0. 


Register A6 now points within the routine's stack frame; the routine can locate 
its parameters and local variables by indexing with respect to this register 
(see Figure 5). The register itself points to its own saved contents, which are 
often (but needn't necessarily be) the frame pointer of the calling routine. The 
parameters and return address are found at positive offsets from the frame 
pointer. 


high memory 


Previous shack wontents 


Function result [iF any | 


First parameter 


“88) 
sa 
stack Lame 
(246) ——> previous [AG] 
frame 


reaner local variables 


(SP) F 


low Memory 


Figure 5—Frame Pointer 
Figure 5—Frame Pointer 


Since the saved contents of the frame pointer register occupy a long word (four 
bytes) on the stack, the return address is located at 4(A6) and the last 
parameter at 8(A6). This is followed by the rest of the parameters in reverse 
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order, and finally by the space reserved for the function result, if any. The 
proper offsets for these remaining parameters and for the function result depend 
on the number and types of the parameters, according to the table above under 
"Stack Based Routines". If the LINK instruction allocated stack space for any 
local variables, they can be accessed at negative offsets from the frame 
pointer, again depending on their number and types. 


At the end of the routine, the instruction 
UNLK A6 


reverses the process: First it releases the local variables by setting the 
stack pointer equal to the frame pointer (A6), then it pops the saved contents 
back into register A6. This restores the register to its original state and 
leaves the stack pointer pointing to the routine's return address. 


A routine with no parameters can now just return to the caller with an RTS 
instruction. But if there are any parameters, it's the routine's responsibility 
to pop them from the stack before returning. The usual way of doing this is to 
pop the return address into an address register, increment the stack pointer to 
remove the parameters, and then exit with an indirect jump through the register. 


Remember that any routine called from Pascal must preserve registers A2-A6 and 
D3-D7. This is usually done by saving the registers that the routine will be 
using on the stack with a MOVEM instruction, and then restoring them before 
returning. Any routine you write that will be accessed via the trap mechanism - 
for instance, your own version of a Toolbox or Operating System routine that 
you've patched into the trap dispatch table - should observe the same 
conventions. 


Putting all this together, the routine should begin with a sequence like 


MyRoutine LINK A6,#-dd ;set up frame pointer- - 
dd = number of bytes 
of local variables 
...or whatever 
registers you use 


MOVEM.L A2-A4/D3-D7, - (SP) 


. 
i 
. 
| 
. 
| 
. 
Si 


and end with something like 


MOVEM.L (SP)+,A2-A4/D3-D7 ;restore registers 


UNLK A6 ;restore frame pointer 

MOVE.L (SP)+,Al ;save return address in an 
; available register 

ADD .W #pp,SP ;pop parameters- - 


; pp = number of bytes 
; of parameters 
JMP (Al) ;return to caller 


Notice that A6 doesn't have to be included in the MOVEM instructions, since 
it's saved and restored by the LINK and UNLK. 
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SUMMARY 


Variables 

OneOne $00010001 

MinusOne $FFFFFFFF 

Lo3Bytes SOOFFFFFF 

Scratch20 20-byte scratch area 

Scratch8 8-byte scratch area 

ToolScratch 8-byte scratch area 

ApplScratch 12-byte scratch area reserved for use by applications 
ROMBase Base address of ROM 

RAMBase Trap dispatch table's base address for routines in RAM 
CurrentA5 Address of boundary between application globals 


and application parameters 
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Further Reference: 


Technical Note #21, QuickDraw's Internal Picture Definition 
Technical Note #88, Signals 

Technical Note #103, MaxApplZone & MoveHHi from Assembly Language 
Technical Note #156, Checking for Specific Functionality 

Technical Note #164, MPW C Functions: To declare or not to declare... 


END OF DOCUMENT 
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